home *** CD-ROM | disk | FTP | other *** search
/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / IDE / SUBARTIC / SUB_ARCT / INPUT / SNAP_TAR.JAV < prev    next >
Encoding:
Text File  |  1996-10-04  |  13.0 KB  |  288 lines
  1.  
  2. package sub_arctic.input;
  3.  
  4. import sub_arctic.lib.interactor;
  5. import java.awt.Point;
  6.  
  7. /** 
  8.  * This interface provides the input protocol for objects which are the 
  9.  * targets of snapping.  Normally these objects are stationary while
  10.  * snap_draggable objects are dragged.  Where the right conditions occur, 
  11.  * feedback is produced which snaps the objects together in 
  12.  * some way (typically by pulling the dragged object to the target object).
  13.  * Snapping is considered to be "from" snap_draggable objects (called the 
  14.  * "drag" objects) "to" snap_targetable objects (called the "target" objects).
  15.  * Both this protocol and the snap_draggable protocol are managed and 
  16.  * delivered by the snap_drag_agent.<p>
  17.  *
  18.  * Snapping requires a two part test.  The first part is geometric.  In this 
  19.  * part we determine if a feature point of the drag object is close enough
  20.  * geometrically to snap to the target.  If this test passes, then a second
  21.  * semantic test is performed to determine if the two objects are semantically
  22.  * compatible (this second test by snap_from_ok() may involve type tests 
  23.  * and/or exchange of information between the drag and target objects).  If
  24.  * both snapping tests succeed, and the snap is the closest candidate snap, 
  25.  * the snap will occur.<p>
  26.  * 
  27.  * If their are no suitable snaps, but some snaps pass the geometric test 
  28.  * (i.e., are close enough) then "anti-snaps" will be considered.  An 
  29.  * anti-snap is designed to provide feedback about a negative condition -- 
  30.  * it is typically used to produce a kind of dynamic "error message" that 
  31.  * indicates why a geometrically possible snap is not semantically suitable.  
  32.  * Anti-snaps must pass a second semantic test (performed by 
  33.  * anti_snap_from_ok()) before they are activated.<p>
  34.  *  
  35.  * @see sub_arctic.input.snap_draggable
  36.  * @see sub_arctic.input.snap_drag_agent
  37.  * @author Scott Hudson
  38.  */
  39. public interface snap_targetable extends interactor {
  40.  
  41.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  42.  
  43.   /** 
  44.    * Determine if the given point (in local coordinates) is close enough
  45.    * to snap to this object (and return the square of its distance, and 
  46.    * the point snapped to).  This is a geometric test only.  To maintain 
  47.    * uniformity, objects should normally report a snap here if the square 
  48.    * of the distance to the point is less than or equal to 
  49.    * snap_drag_agent.snap_dist2().  The return_dist2 object should be 
  50.    * modified so that it contains the square of the distance from the point 
  51.    * to the target.  The return_snap_pt object should be modified to return 
  52.    * the final snap point.  Both return_dist2 and return_snap_pt are ignored
  53.    * if the routine returns false.
  54.    * 
  55.    * @param pt             the point being tested (in local coordinates).
  56.    * @param return_dist2   to be modified to contain the square of the distance
  57.    *                       to the point (ignored if false is returned).
  58.    * @param return_snap_pt to be modified to contain the final snap target 
  59.    *                       point in local coordinates (ignored if false is 
  60.    *                       returned).
  61.    * @return boolean indicating whether snap is geometrically accepted.
  62.    */
  63.   public boolean point_snaps(
  64.     Point      pt, 
  65.     int_holder return_dist2, 
  66.     Point      return_snap_pt);
  67.  
  68.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  69.  
  70.   /** 
  71.    * Determine if a geometrically accepted snap should be semantically 
  72.    * accepted.  Normally target objects only accept snaps from drag
  73.    * objects that meet certain qualifications.  This routine is responsible 
  74.    * for determining if the given object and the given feature point within 
  75.    * that object meets the current criteria for a snap.  This normally 
  76.    * involves determining whether the drag object implements a certain 
  77.    * (application specific) interface, then using the protocol of that 
  78.    * interface to query the properties of the drag object.
  79.    * 
  80.    * @param pt              the pre-snap location of the feature point being 
  81.    *                        tested.
  82.    * @param drag_obj        the drag object being tested.
  83.    * @param feature_pt_indx the index of the feature point (within drag_obj)
  84.    *                        being tested.
  85.    * @return whether the snap is acceptable.
  86.    */
  87.   public boolean snap_from_ok(
  88.     Point          pt, 
  89.     snap_draggable drag_obj, 
  90.     int            feature_pt_indx);
  91.    
  92.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  93.  
  94.   /** 
  95.    * Determine if a geometrically accepted snap which has been semantically
  96.    * rejected (by snap_from_obj()) should provide anti-snap feedback.
  97.    * (Anti-snap feedback supplies a sort of dynamic error message that 
  98.    * indicates why a snap is illegal.)  This may involve determining whether 
  99.    * the drag object implements a certain  (application specific) interface, 
  100.    * then using the protocol of that interface to query the properties of the 
  101.    * drag object.  In other cases a generic "wrong type" anti-snap might be
  102.    * performed.<p>
  103.    * 
  104.    * If no anti-snap is to be applied, null is returned.  Otherwise an object 
  105.    * with information about the reason for the anti-snap is returned. This 
  106.    * object will then be passed to various anti-snap calls. 
  107.    *
  108.    * @param pt              the pre-snap location of the feature point being 
  109.    *                        tested.
  110.    * @param drag_obj        the drag object being tested.
  111.    * @param feature_pt_indx the index of the feature point (within drag_obj) 
  112.    *                        being tested.
  113.    * @return Object null for no anti-snap.  If anti-snap feedback is desired a 
  114.    *                non-null object is returned (which is later passed to 
  115.    *                various anti-snap routines in the protocol).
  116.    */
  117.    public Object anti_snap_from_ok(
  118.     Point          pt, 
  119.     snap_draggable drag_obj, 
  120.     int            feature_pt_indx);
  121.  
  122.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  123.  
  124.   /** 
  125.    * Do the feedback corresponding to a snap from the given drag object.
  126.    *
  127.    * @param event           evt             the event "causing" the snap.
  128.    * @param Point           orig_pt         where the dragged object would be 
  129.    *                                        without the snap.
  130.    * @param Point           snap_pt         the snap point.
  131.    * @param snap_draggable  drag_obj        the dragged object we are snapping 
  132.    *                                        from.
  133.    * @param int             feature_pt_indx the feature point of that object 
  134.    *                                        that we are snapping with.
  135.    * @param Object          user_info       the user info for this input.
  136.    * @return boolean indicating if the input has been consumed.
  137.    */
  138.   public boolean snap_from(
  139.     event          evt, 
  140.     Point          orig_pt, 
  141.     Point          snap_pt, 
  142.     snap_draggable drag_obj, 
  143.     int            feature_pt_indx,
  144.     Object         user_info);
  145.  
  146.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  147.  
  148.   /** 
  149.    * Perform feedback while a snap is active.
  150.    *
  151.    * @param event           evt             the event "causing" the snap.
  152.    * @param Point           orig_pt         where the dragged object would be 
  153.    *                                        without the snap.
  154.    * @param Point           snap_pt         the snap point.
  155.    * @param snap_draggable  drag_obj        the dragged object we are snapping 
  156.    *                                        from.
  157.    * @param int             feature_pt_indx the feature point of that object 
  158.    *                                        that we are snapping with.
  159.    * @param Object          user_info       the user info for this input.
  160.    * @return boolean indicating if the input has been consumed.
  161.    */
  162.   public boolean snap_feedback(
  163.     event          evt, 
  164.     Point          orig_pt, 
  165.     Point          snap_pt, 
  166.     snap_draggable drag_obj, 
  167.     int            feature_pt_indx,
  168.     Object         user_info);
  169.  
  170.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  171.  
  172.   /** 
  173.    * Remove feedback for a snap that is now being broken. 
  174.    *
  175.    * @param event           evt             the event "causing" the unsnap.
  176.    * @param Point           orig_pt         where the dragged object would be 
  177.    *                                        without the snap.
  178.    * @param Point           snap_pt         the snap point.
  179.    * @param snap_draggable  drag_obj        the dragged object we are 
  180.    *                                        unsnapping from.
  181.    * @param int             feature_pt_indx the feature point of that object 
  182.    *                                        that we are unsnapping with.
  183.    * @param Object          user_info       the user info for this input.
  184.    * @return boolean indicating if the input has been consumed.
  185.    */
  186.   public boolean unsnap_from(
  187.     event          evt, 
  188.     Point          orig_pt, 
  189.     Point          snap_pt, 
  190.     snap_draggable drag_obj, 
  191.     int            feature_pt_indx,
  192.     Object         user_info);
  193.     
  194.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  195.  
  196.   /** 
  197.    * Do anti-snap feedback corresponding to an anti-snap from the given 
  198.    * drag object.
  199.    *
  200.    * @param event           evt             the event "causing" the anti-snap.
  201.    * @param Point           orig_pt         where the dragged object would be 
  202.    *                                        without the anti-snap.
  203.    * @param Point           snap_pt         the anti-snap point.
  204.    * @param snap_draggable  drag_obj        the dragged object we are 
  205.    *                                        anti-snapping from.
  206.    * @param int             feature_pt_indx the feature point of that object 
  207.    *                                        that we are anti-snapping with.
  208.    * @param Object          user_info       the user info for this input.
  209.    * @return boolean indicating if the input has been consumed.
  210.    */
  211.   public boolean anti_snap_from(
  212.     event          evt, 
  213.     Point          orig_pt, 
  214.     Point          snap_pt, 
  215.     snap_draggable drag_obj, 
  216.     int            feature_pt_indx,
  217.     Object         anti_snap_info,
  218.     Object         user_info);
  219.  
  220.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  221.  
  222.   /** 
  223.    * Perform feedback while an anti-snap is active.
  224.    *
  225.    * @param event           evt             the event "causing" the anti-snap.
  226.    * @param Point           orig_pt         where the dragged object would be 
  227.    *                                        without the anti-snap.
  228.    * @param Point           snap_pt         the anti-snap point.
  229.    * @param snap_draggable  drag_obj        the dragged object we are 
  230.    *                                        anti-snapping from.
  231.    * @param int             feature_pt_indx the feature point of that object 
  232.    *                                        that we are anti-snapping with.
  233.    * @param Object          user_info       the user info for this input.
  234.    * @return boolean indicating if the input has been consumed.
  235.    */
  236.   public boolean anti_snap_feedback(
  237.     event          evt, 
  238.     Point          orig_pt, 
  239.     Point          snap_pt, 
  240.     snap_draggable drag_obj, 
  241.     int            feature_pt_indx,
  242.     Object         anti_snap_info,
  243.     Object         user_info);
  244.  
  245.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  246.  
  247.   /** 
  248.    * Remove anti-snap feedback for an anti-snap that is now being broken.
  249.    *
  250.    * @param event           evt             the event "causing" the unanti-snap.
  251.    * @param Point           orig_pt         where the dragged object would be 
  252.    *                                        without the anti-snap.
  253.    * @param Point           snap_pt         the anti-snap point.
  254.    * @param snap_draggable  drag_obj        the dragged object we are 
  255.    *                                        unanti-snapping from.
  256.    * @param int             feature_pt_indx the feature point of that object 
  257.    *                                        that we are unanti-snapping with.
  258.    * @param Object          user_info       the user info for this input.
  259.    * @return boolean indicating if the input has been consumed.
  260.    */
  261.   public boolean unanti_snap_from(
  262.     event          evt, 
  263.     Point          orig_pt, 
  264.     Point          snap_pt, 
  265.     snap_draggable drag_obj, 
  266.     int            feature_pt_indx,
  267.     Object         anti_snap_info,
  268.     Object         user_info);
  269.  
  270.   /* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . */
  271. }
  272. /*=========================== COPYRIGHT NOTICE ===========================
  273.  
  274. This file is part of the subArctic user interface toolkit.
  275.  
  276. Copyright (c) 1996 Scott Hudson and Ian Smith
  277. All rights reserved.
  278.  
  279. The subArctic system is freely available for most uses under the terms
  280. and conditions described in 
  281.   http://www.cc.gatech.edu/gvu/ui/sub_arctic/sub_arctic/doc/usage.html 
  282. and appearing in full in the lib/interactor.java source file.
  283.  
  284. The current release and additional information about this software can be 
  285. found starting at: http://www.cc.gatech.edu/gvu/ui/sub_arctic/
  286.  
  287. ========================================================================*/
  288.